Developer CD Series 1997 January: Mac OS SDK/Dev.CD Jan 97 SDK1.toast/Development Kits (Disc 1)/AppleScript/Development Tools/Tools Goodies/AEGizmos 1.4.1/Documentation/AE Builder⁄Printer Doc.dp

Common Ground | 1995-03-20 | 60.3 KB | 955 lines | [CGDC/CGVM]

Palatino
Apple Events
 Builder/Printer
AEGizmos Version 1.4
Jens Peter Alfke
20 March 1995
 Apple Computer, Inc. 1991
New York
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
Contents
Contents
)4 ................................
)` ................................
)` ................................
..............
Introduction
)F ................................
)` ................................
)` ................................
..........
OK, What Is It?
s New?
How To Call the Functions
 ................................
)` ................................
................
AEBuild
AEBuildParameters
AEBuildAppleEvent
AEPrint
Descriptor-String Syntax
 ................................
)` ................................
...................
Basic Types
Coercion
Lists
Records
Apple Events
Substituting Parameters
Descriptor-String Grammar
 ................................
)` ................................
............
An Example & Timing Comparison
 ................................
..............................
#C Code Using Object-Packing Library
Descriptor String
AEBuild Call
Timing Conclusions
The Demo Program
)m ................................
)` ................................
...........................
The Header Files
)^ ................................
)` ................................
)` ................................
    AEBuild.h
AEBuildGlobals.h
    AEPrint.h
New York
Palatino
The AppleEvent Builder/Printer
20 March 1995
Page
Introduction
OK, What Is It?
KEven with the helpful routines in AEPackObject.h that assemble common Apple
Oevent object descriptors, building descriptors and events is still a pain. I
Lwritten a library of a few functions that make it quick and easy to build or
@display Apple event descriptors and the Apple events themselves.
Courier
AEBuild
)*@ function takes a format string
 a description in a very simple
fNlanguage of an Apple event descriptor
 and generates a real descriptor (which
3could be a record or list or event) out of it. The
AEPrint
 function does the reverse:
fUgiven an Apple event descriptor, list or record, it prettyprints it to a string. (The
resulting string, if sent to
AEBuild
, would reproduce the original
AEDesc
structure.)
AEBuild
)*H can plug variable parameters into the structures it generates
 as with
printf
)$I, all you do is put marker characters in the format string and supply the
f-parameter values as extra function arguments.
0The benefits of using this library are fourfold:
Zapf Dingbats
s easier for you to write the code to build Apple event structures. You
Fonly have to remember one function call and a few simple syntax rules.
1Your resulting code is also easier to understand.
-As of version 1.2, your code is even faster:
AEBuild
 is three to four times
Cas fast as the regular Apple Event Manager routines at constructing
,complex structures. (Your mileage may vary.)
#Your code is smaller: the code for
AEBuild
 and the AEStream library is
Iabout 6k in size, and the overhead for each call is minimal. (Most of the
Jdescriptor string consists of the same four-letter codes you
d be using in
?your program code anyway, and the strings can even be stored in
!resources for more code savings.)
AEPrint
)*4 helps in debugging programs, by turning mysterious
AEDesc
$structures into human-readable text.
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
 What
s New?
In version 1.3.2:
Courier
AEPrint
 no longer uses the
stdio
+ library. This should help reduce code size
^0(and eliminate some problems in code resources).
And in version 1.3.3:
LAfter a brilliant suggestion by Rob Dye, AEPrint now uses the built in float
^7to-text coercion to display floating-point descriptors.
EFixed a possible problem with AEBuild input strings containing Return
.characters, in the MPW version of the library.
And in version 1.4:
NFixed an AEPrint bug that was changing the type of list descriptors to
LFixed problems parsing non-ascii characters (notably
) in the CodeWarrior
version of the library.
 descriptors are built properly (one byte, not two.)
JFixed AEPrint quoting problems on 4-char codes that could cause the output
to be unparseable by AEBuild.
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
How To Call the Functions
fRThese are all C functions. They all take variable number s of arguments, so they
Tbe difficult to call from Pascal, anyway. (People keep telling me it
s possible, but
Tno one has ever sent me a Pascal header for these functions; if anyone does so, I
include it in future versions.)
AEBuild
Courier
OSErr
9AEBuild(  AEDesc *desc, const char *descriptorStr, ... ),
@vAEBuild( AEDesc *desc, const char *descriptorStr, void *args );
AEBuild
)*K reads a null-terminated descriptor string (usually a constant, although it
f@could come from anywhere), parses it and builds a corresponding
AEDesc
fQstructure. (Don
t worry, I
ll describe the syntax of the descriptor string in the
Mnext section.) If the descriptor string contains magic parameter-substitution
characters (
) then corresponding values of the correct type must be supplied
f$as function arguments, just as with
printf
vAEBuild
 is analogous to
vprintf
)*.: Instead of passing the parameters along with
the function, you supply a
va_list
, as defined in
<stdarg.h>
, that points to the
f*parameter list. It
s otherwise identical.)
AEBuild
 returns an
OSErr
5. Any errors returned by Apple Event Manager routines
fSwhile building the descriptor will be sent back to you. The most likely results are
memFullErr
 and
errAECoercionFail
. Also likely is
aeBuildSyntaxErr
, resulting
fQfrom an incorrect descriptor string. (Make sure to debug your descriptor strings,
Eperhaps using the demo application, before you put them in programs!)
The basic version of
AEBuild
)*3 just reports that a syntax error occurred, without
fOgiving any additional information. If you want to know more (perhaps the string
Ocame from a user, to whom you
d like to report a helpful error message) you can
Tuse the other version of the library. This version includes a wee bit of extra code,
Sand two global variables that will contain useful information after a syntax error:
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
Courier
extern AEBuild_SyntaxErrType
AEBuild_ErrCode;
extern long
AEBuild_ErrPos;
AEBuild_ErrCode
)Z@ is an enumerated value that will contain a specific error code.
N*The error codes are defined in AEBuild.h.
AEBuild_ErrPos
 will contain the index
NRinto the descriptor string at which the error occurred: usually one character past
the end of the offending token.
AEBuildParameters
OSErr
)$HAEBuildParameters(  AppleEvent *event, const char *descriptorStr, ... );
AEBuildParameters
)f7 adds parameters and/or attributes to an existing Apple
event.
descriptorStr
)N5 specifies the parameters (required and optional) and
NIattributes. Its syntax is described below (see especially the Apple Event
GDescriptor Strings subsection); it
s almost the same as the syntax for
AEBuild
N'with a few additions and modifications.
vAEBuildParameters
 is analogous to
vprintf
)*#: Instead of passing the parameters
N&along with the function, you supply a
va_list
, as defined in
<stdarg.h>
, that
N8points to the parameter list. It
s otherwise identical.)
AEBuildAppleEvent
AEBuildAppleEvent(
)l'AEEventClass theClass, AEEventID theID,
<DescType addressType, void *addressData, long addressLength,
#short returnID, long transactionID,
AppleEvent *event,
!const char *descriptorStr, ... );
AEBuildAppleEvent
)f     is like
AEBuild
)*% but builds an Apple event, including
N<parameters and attributes. Or, you could say that it
s like
AEBuildParameters
creates the event from scratch.
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
f7Most of the parameters are just like the parameters to
Courier
AECreateAppleEvent
fNalthough you pass the target address data directly, instead of via a pre-built
9descriptor. The resulting Apple event will appear in the
event
 parameter.
descriptorStr
)NA specifies the parameters (required and optional) and attributes.
fPThe syntax is described below (see especially the Apple Event Descriptor Strings
4subsection); it
s almost the same as the syntax for
AEBuild
, with a few additions
and modifications.
vAEBuildAppleEvent
 is analogous to
vprintf
)*#: Instead of passing the parameters
f&along with the function, you supply a
va_list
, as defined in
<stdarg.h>
, that
f8points to the parameter list. It
s otherwise identical.)
AEPrint
*":OSErr AEPrint( AEDesc *desc, char *bufStr, long bufSize );
AEPrint
)*" reads the Apple event descriptor
 and writes a corresponding
f0descriptor string into the string pointed to by
bufStr
. It will write no more than
bufSize
)*J characters, including the trailing null character. Any errors returned by
fSApple Event Manager routines will be returned to the caller; this isn
t very likely
unless the
AEDesc
 structure is somehow corrupt.
f+The descriptor string produced, if sent to
AEBuild
, will build a descriptor
identical to the original one.
AEPrint
 tries to detect
)M    AERecords
 that have been
fOcoerced to other types and print them as coerced records. Structures of unknown
type that can
t be coerced to
    AERecords
 are dumped as hex data.
AEPrint
)*I can also print complete Apple events as well as regular descriptors. The
fAsyntax of the resulting string for an event is like that used by
AEBuildParameters
AEBuildAppleEvent
, except that:
GThe string begins with the event class and ID separated by a backslash.
1the parameter list is surrounded by curly braces.
LAttributes are also displayed; they look like parameters but are preceded by
Zapf Dingbats
The builder functions do
  accept this event syntax yet.
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
AEPrintSize
Courier
*"7OSErr AEPrintSize( AEDesc *desc, long *bufSizeNeeded );
AEPrintSize
 computes the buffer size that
AEPrint
 would require if given the
NVsame descriptor. (The size is equal to the string length, plus 1 byte for the trailing
'null.) This is handy for pre-flighting
AEPrint
)*$, if you want to allocate the buffer
N6dynamically  instead of relying on one of fixed size .
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
Descriptor-String Syntax
fSThe real meat of all this, of course, is the syntax of the descriptor strings. It
Ipretty simple: basic data types like numbers and strings can be described
Odirectly, and then built up into lists and records. I
ve even provided a pseudo
fLBNF grammar (next section) for those of you who actually enjoy reading those
things.
Basic Types
The fundamental data types are:
Examples
)c    Type-code
Description
Integer
Courier
-5678
'long'
'shor'
A sequence of decimal digits,
optionally preceded by a minus
sign.
f    Enum/Type
longint
'long'
'8-)'
'enum'
(Use coercion
to change to
'type')
]!A magic four-letter code. Will be
truncated or padded with spaces
"to exactly four characters. If you
put straight or curly single
] quotes around it, it can contain
 any characters. If not, it can
contain any of:
:-,([{}])
and can
t begin with a digit.
String
A String.
Multiple lines
are okay.
'TEXT'
Any sequence of characters
within open and close
curly
]!quotes. Won
t be null-terminated.
Hex Data
4170706C65
0102 03ff
     e b 6 c
(Must be
coerced to
some type)
An even number of hex digits
between French quotes (Option
]!\, Option-Shift-\). Whitespace is
ignored.
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
Zapf Dingbats
HYes, you have to use the actual four-letter codes for enums, type codes,
Ikeywords and object types, instead of the mnemonic constants. Luckily the
Fcodes are semi-mnemonic anyway. I did it this way to avoid the massive
Koverhead, both in code size and execution speed, of a symbol table. You can
Nfind the definitions of the constants in the text file
AEObjects.h
, which is
2part of the Apple Events Object Support Library.
Warning
)D?Watch out for four-letter-codes that contain special characters
Blike commas, parens, braces, or non-trailing spaces, or that begin
with a special character like
Courier
 . Put these in single quotes to
avoid syntax errors.
Coercion
HAny basic element (except a hex string) by itself is a descriptor, whose
LdescriptorType is as given in the table. You can coerce a basic element to a
Sdifferent type by putting it in parentheses with a type-code placed before it. Here
are some examples:
sing(1234)
type(line)
long(CODE)
hexd(
A String
'blob'(
4170706C65
4Coercions of numeric values are effected by calling
AECoerceDesc
; if the
coercion fails, you
ll get an
errAECoercionFail
 error returned to you.
^*Coercions of other types just replace the
descriptorType
 field of the
AEDesc
Hex strings
must
=be coerced to something, since they have no intrinsic type.
NGYou can also coerce nothing, to get a descriptor with zero-length data:
emty()
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
f+Even the type can be omitted, leaving just
Courier
, in which case the type is '
null'
Lists
To make an
AEDescList
)<7, just enclose a comma-separated list of descriptors in
square brackets. For example:
[123, -456,
et cetera
[sing(1234), long(CODE),
wheels
within wheels
fWThe elements of a list can be of different types, and a list can contain other lists or
 records (see below) as elements.
ELists cannot be coerced to other types; the type of a list is always
'list'
Records
AERecord
)0E is indicated by a comma-separated list of elements enclosed in curly
fQbraces. Each element of a record consists of a keyword (a type-code, as described
"under Basic Types) followed by a
, followed by a value, which can be any
f@descriptor: a basic type, a list or another record. For example:
{x:100, y:-100}
3{'origin': {x:100, y:-100}, extent: {x:500, y:500},
 cont: [1, 5, 25]}
f The default type of a record is
'reco'
)$'. Many of the Apple Events Object Model
structures are
)K    AERecords
)65 that have been coerced to some other data type, like
'indx'
 or '
whos'
?. You can coerce a record structure to any type by preceding it
with a type code. For example:
rang{ star: 5, stop: 6}
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
Zapf Dingbats
Warning
)D&Coercing to an existing type, such as
Courier
'bool'
'TEXT'
, is a bad
/idea. Anyone parsing the descriptor (including
AEPrint
) will
:recognize the type and assume that the data has the normal
Cinterpretation, which in this case it wouldn
t. Bad to awful things
would happen. Don
t do it.
Apple Events
KThe syntax of the formatting string for an entire Apple event (as passed to
AEBuildAppleEvent
)f=) is almost identical to that of a record. Each keyed element
NJspecified in the string becomes a parameter or attribute of the event. The
differences are:
AThere are no curly-braces at the beginning and end of the string.
?The character
 before a parameter keyword makes it optional.
Warning
)D)The keyword for the direct parameter is
. Remember to
?put single-quotes around it, or the parser will see the first
and think it
s found a number.
NMHere
s an example of how to construct an Open Selection event for the Finder:
AliasHandle parent, itemToOpen;
&const OSType finderSignature = 'MACS';
AppleEvent event;
OSErr err;
)// Construct the aliases here (not shown)
err= AEBuildEppleEvent(
'FNDR', 'SOPE',
=typeApplSignature, @finderSignature, sizeof(finderSignature),
)kAutoGenerateReturnID, kAnyTransactionID,
&event,
// Event to be created
: alis(@@), fsel: [alis(@@)]
// Format string
parent,
// param for 1st @@
itemToOpen
// param for 2nd @@
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
Substituting Parameters
GTo plug your own values into the midst of a descriptor, use the magic
Courier
character. You can use
 anywhere you can put a basic element like an integer.
Each
 is replaced by a value taken from the parameter list sent to the
AEBuild
fIfunction. The type of value created depends on the context in which the
f&used: in particular, how it
s coerced.
Type Coerced to:
Type of fn parameter read:
    Comments:
No coercion
AEDesc*
]    A plain
 will be replaced with a
descriptor parameter.
f    Numeric (
short
short
float
short double
double
Remember that THINK C
double
corresponds to type
'exte'
char*
]&Pointer to a null-terminated C string.
Any other type
 followed by
void*
)9&Expects a length parameter followed by
!a pointer to the descriptor data.
Zapf Dingbats
    Important
Note particularly: that
# parameters must be null-terminated
@strings, although the resulting descriptor data will not be null
.terminated; and that the general case expects
 parameters: the
s size and location.
f<In addition, you can substitute data from a handle by using
 signs. An
fLparameter will read a single handle from the parameter list and use the data
?pointed to by that handle as the value of the descriptor. The
 must be
coerced so that
AEBuild
)*5 will know what type to make the descriptor; however,
fAthe type coerced to can be anything (the table above is ignored.)
NThis mechanism is still a bit limited, and may well be improved in the future.
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
Descriptor-String Grammar
NNSince no language, however small, can be taken seriously unless it comes fully
Lequipped with a formidable-looking BNF grammar specification, I here present
Hone. No attempt has been made to prevent Messrs. Backus and/or Naur from
(rolling over in their respective graves.
Character Classification:
whitespace
digit
paren, bracket,
braces
single-quote
double quotes
hex quotes
colon
comma
at-sign
r    identchar
any other printable character
Tokens:
    ident ::=
)l    identchar
    identchar
digit
Padded/truncated
    character
to exactly 4 chars
integer ::=
digit
Just as in C
string ::=
    character
hexstring ::=
hexdigit
whitespace
Even no. of digits, please
Grammar Rules for AEBuild:
formatstring ::=
This is the top level of syntax
obj ::=
Single AEDesc; shortcut for
    structure
Un-coerced structure
ident
 structure
Coerced to some other type
structure ::=
 data
Single AEDesc
 objectlist
AEList type
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
 keywordlist
AERecord type
objectlist ::=
blank
Comma-separated list of things
obj [
 obj ]
keywordpair ::=
ident
Keyword/value pair
keywordlist ::=
blank
List of said pairs
keywordpair [
 keywordpair ]
data ::=
Gets appropriate data from fn param
integer
'shor' or 'long' unless coerced
ident
A 4-char type code ('type') unless coerced
string
Unterminated text; 'TEXT' type unless coerced
    hexstring
Raw hex data;
 be coerced to some type!
f$Grammar Rules for AEBuildAppleEvent:
eventstring ::=
evtkeywordlist
Top level syntax for AEBuildAppleEvent
evtkeywordpair ::=
ident
Keyword/value pair
evtkeywordlist ::=
blank
List of said pairs
evtkeywordpair [
 evtkeywordpair ]
f)There. Now it
s all crystal-clear, right?
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
An Example & Timing Comparison
NRAs an example, I
ll take a C function to generate an object descriptor (taken from
La Pascal example in the Object Model ERS, fleshed out and with gobs of error
+checking added) and turn it into a call to
Courier
AEBuild
. The object descriptor we want
to generate is:
>First line of document 'Spinnaker' whose first word is 'April'
and whose second word is 'is'
NCThen I
ll execute both functions and compare their execution times.
*4#C Code Using Object-Packing Library
OSErr
6BuildByHand( AEDesc *dDocument, AEDesc *theResultObj )
OSErr err;
BAEDesc dObjectExamined, dNum, dWord1, dWord2, dAprilText, dIsText,
O   dComparison1, dComparison2, dLogicalTerms, dTheTest, dLineOne, dTestedLines;
dObjectExamined.dataHandle =
4/* Zero things to start out with so we can safely */
dNum.dataHandle =
4/* execute our fail code if things don't work out */
dWord1.dataHandle =
dWord2.dataHandle =
dAprilText.dataHandle =
dIsText.dataHandle =
dComparison1.dataHandle =
dComparison2.dataHandle =
dLogicalTerms.dataHandle =
dTheTest.dataHandle =
dLineOne.dataHandle =
dTestedLines.dataHandle =
r;if( err= AECreateDesc( 'exmn', NIL, 0, &dObjectExamined ) )
goto fail;
r'if( err= MakeIndexDescriptor(1,&dNum) )
goto fail;
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
Courier
Gif( err= MakeObjDescriptor( 'word', &dObjectExamined, formIndex, &dNum,
false, &dWord1) )
goto fail;
:if( err= AECreateDesc( 'TEXT', "April", 5, &dAprilText ) )
goto fail;
AEDisposeDesc(&dNum);
'if( err= MakeIndexDescriptor(2,&dNum) )
goto fail;
Gif( err= MakeObjDescriptor( 'word', &dObjectExamined, formIndex, &dNum,
true, &dWord2) )
goto fail;
4if( err= AECreateDesc( 'TEXT', "is", 2, &dIsText ) )
goto fail;
Rif( err= MakeCompDescriptor( '=   ', &dAprilText, &dWord1, true, &dComparison1 ) )
goto fail;
.if( err= MakeCompDescriptor( '=   ', &dIsText,
"  &dWord2, true, &dComparison2 ) )
goto fail;
8if( err= AECreateList( NIL, 0, false, &dLogicalTerms ) )
goto fail;
6if( err= AEPutDesc( dLogicalTerms, 1, dComparison1 ) )
goto fail;
6if( err= AEPutDesc( dLogicalTerms, 2, dComparison2 ) )
goto fail;
AEDisposeDesc(&dComparison1);
AEDisposeDesc(&dComparison2);
Jif( err= MakeLogicalDescriptor( &dLogicalTerms, 'AND ', true, &dTheTest) )
goto fail;
Hif( err= MakeObjDescriptor(classLine,&dDocument,formTest,&dTheTest,true,
&dTestedLines) )
goto fail;
+if( err= MakeIndexDescriptor(1,&dLineOne) )
goto fail;
Kif( err= MakeObjDescriptor( classLine, &dTestedLines, formIndex, &dLineOne,
true, theResultObj ) )
goto fail;
return noErr;
fail:
+/* Clean up in case we couldn't build it */
AEDisposeDesc(theResultObj);
 AEDisposeDesc(&dObjectExamined);
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
Courier
AEDisposeDesc(&dNum);
AEDisposeDesc(&dWord1);
AEDisposeDesc(&dWord2);
AEDisposeDesc(&dAprilText);
AEDisposeDesc(&dIsText);
AEDisposeDesc(&dComparison1);
AEDisposeDesc(&dComparison2);
AEDisposeDesc(&dLogicalTerms);
AEDisposeDesc(&dTheTest);
AEDisposeDesc(&dLineOne);
AEDisposeDesc(&dTestedLines);
return err;
*!8MPW 3.2b5 C compiled this into 816 bytes of object code.
II found that the average time to execute this function was 0.0188 seconds
&(Quadra 700) or 0.0113 seconds (IIfx).
* Use this figure for comparison only; your
NMtimes may vary. The timing is especially dependent on the number of blocks in
Fthe heap, since so many block allocations and disposals are happening.
Descriptor String
obj{ want:type('line'),
:     from: obj{ want: type('line'), from: @, form: 'test',
                seld: logi{
=                           term: [comp{ relo:=, obj1:
April
-                                        obj2:
X                              obj{ want:type('word'), from:exmn(), form:indx, seld:1 }},
:                                  comp{ relo:=, obj1:
-                                        obj2:
W                              obj{ want:type('word'), from:exmn(), form:indx, seld:2 }}
#                                 ],
#                           logc:AND
                         }
              },
     form: 'indx',
     seld: 1
\ Yes, it really took half again as long on a Quadra! I think that cache flushing during the
NOcall is responsible. (It barely slows down at all when you disable the caches.)
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
AEBuild Call
Courier
char descriptor[] =
2/* Same descriptor string as above. Note clever */
"obj{ want:type('line'),"
//* method used to break string across lines. */
f;    "from: obj{ want: type('line'), from: @, form: 'test',"
/* Note parameter here */
               "seld: logi{"
>                          "term: [comp{ relo:=, obj1:
April
.                                       "obj2:"
Y                             "obj{ want:type('word'), from:exmn(), form:indx, seld:1 }},"
;                                 "comp{ relo:=, obj1:
.                                       "obj2:"
X                             "obj{ want:type('word'), from:exmn(), form:indx, seld:2 }}"
$                                "],"
$                          "logc:AND"
                        "}"
             "},"
    "form: 'indx',"
    "seld: 1"
,void PackWordDesc( AEDesc *dDocumentObject )
Spinnaker
 descriptor is a parameter */
err = AEBuild(&theResultObj,
descriptorString,
dDocumentObject);
/* AEDesc* parameter for "@" */
*!NMPW 3.2b5 C compiled this into 42 bytes of object code, plus 310 bytes of data
storage for the string.
II found that the average time to execute this function was 0.0049 seconds
P(Quadra 700) or 0.0070 seconds (IIfx). Use this figure for comparison only; your
Ltimes may vary. The timing is dependent on the number of blocks in the heap,
2since heap blocks are being allocated and resized.
Palatino
The Apple Event Builder/Printer
Page
20 March 1995
Timing Conclusions
RWith previous versions of this library, there was a 70% increase in execution time
when using the
Courier
AEBuild
)*1 routine. After delivering the bad news, I wrote:
rEHowever, if speed does become an issue, there is always the option of
turbocharging
AEBuild
5by having it directly build descriptors without going
rOthrough the Apple Event Manager functions at all. This would save an incredible
@number of Memory Manager calls and probably increase performance
severalfold. Anyone using
AEBuild
)will get all these improvements for free.
NSThis is exactly what I did in version 1.1. In fact, I wrote a library (AEStream) to
'do it, so you can do it too. It
s easy.
AEBuild
,is now 1.5 to 4 times as fast (depending on
) as the using the Apple
N5Event Manager and/or Object Packing Library routines.
 (This means that
NKAEStream was responsible for a threefold speed-up in AEBuild. Not bad, when
Eyou take into account other overhead like parsing the format string!)
+Needless to say, if you were already using
AEBuild
 you get this speed increase
absolutely free. Enjoy!
Palatino
The Apple Event Builder/Printer
20 March 1995
Page
The Demo Program
ve included a demonstration program in the distribution. This is a program I
Vused to debug the library. It reads a line of input, uses AEBuild to translate it into
Nan AEDesc, uses AEPrint to translate the AEDesc back into a string, and prints
Qeach resulting string. Error codes are reported, including syntax-error messages.
QThe source code is provided in case you want to see how the functions are called.
Zapf Dingbats
Warning
The demo tool does
% handle parameter substitution (the
Courier
:character). If you try to substitute parameters, messy and
=unpleasant things may happen. Use some numeric value in place
)of parameters, and then replace it with
s after you paste the
string into your program.
E" S71*U
+@A='*
p 0p`P
H9;BE
"&)+-
L,.$2
( @$$
xP(H`X
    G'()*,-./
1"!$?
9:48*
B4+,-.653
    temp.0001
""""""?
Jens Alfke
Apple Computer
Microsoft Word
New York
Zapf Dingbats
Palatino
Courier
bPREC
nPRVS
zCAPN